Purchase your product

You can now initiate your first product purchase. In order to initiate a product purchase from the developer's website and drive the customer into AppDirect hosted checkout, two steps are required. First, you must make an API call to initialize the hosted checkout transaction. Second, you must make the actual redirect of the customer from the developer's website to the AppDirect hosted checkout site.

Product purchases are done through the Hosted Checkout API using the create transaction call. This 'create transaction' operation will create the user and company records (unless they already exist, in which case you need to use the appropriate endpoints listed below), generate a new transaction ID and return it with other useful transaction information, such as the hosted checkout url for redirecting the user.

Method: POST

Endpoints: There are 3 endpoints, depending on the user and company status, as shown below.

• For brand new users: api/hostedCheckout/v1/transactions
• For a new user in an existing company: api/hostedCheckout/v1/companies/{COMPANY_ID}/transactions
• For existing user in an existing company: api/hostedCheckout/v1/companies/{COMPANY_ID}/users/{USER_ID}/transactions

Request attributes

Name	Format	Location	Mandatory	Applicable for type(s)	Applicable for flow(s)	Additional information
token	String	payload	yes	PURCHASE and BILLING_INFO	ALL	AppDirect requires the developer (API caller) to send a unique generated token as part of the initial API request so that AppDirect's backend can associate it with the generated transaction 'ID'. AppDirect will then require the developer to send this token with the received transaction ID together during user redirection to the hosted checkout page. (The 'hostedCheckoutUrl' returned in the response will already contain everything needed to redirect the user, i.e. the token and transaction ID will be part of the URL as parameters.)
type	String	payload	yes	N/A	ALL	Possible values: "PURCHASE" or "BILLING_INFO"
productId	Numeric	payload	only when type = PURCHASE	PURCHASE	ALL "PURCHASE" flows	The developer will only present products to their customers (not product 'plans/editions', which were defined within the marketplace under each created product). Once a customer is redirected to the marketplace from the given product ID, the marketplace will list the available product plans for the customer to choose from. When a subscription has been purchased previously for this given 'productId', the hosted checkout will present a slightly different screen allowing the customer update his existing application subscription (e.g., upgrade the number of users that can use the application).
user.email	String	payload	no	PURCHASE	New customer purchase	The email address for the user to create. Needed when creating a "new" user of a new or existing company, otherwise ignore this parameter and provide a USER_ID instead.
user.firstName	String	payload	no	PURCHASE	New customer purchase	The first name of the user to create. Needed when creating a "new" user of a new or existing company, otherwise ignore this parameter and provide a USER_ID instead.
user.lastName	String	payload	no	PURCHASE	New customer purchase	The last name of the user to create. Needed when creating a "new" user of a new or existing company, otherwise ignore this parameter and provide a USER_ID instead.
user.language	String	payload	no	PURCHASE	New customer purchase	The preferred language of the user to create. The value should follow the list of ISO 639-1 language codes (ex.: 'en', 'fr', etc) and should match an already defined and available language of the marketplace. If not specified, the default user language used will be the default language of the marketplace. Needed when creating a "new" user of a new or existing company, otherwise ignore this parameter and provide a USER_ID instead.
company.name	String	payload	no	PURCHASE	New customer purchase	The company name of the company to create. Needed when creating a new user for a "new" company, otherwise ignore this parameter and provide a COMPANY_ID instead.The first name of the user to create.
COMPANY_ID	String	URL	no	PURCHASE and BILLING_INFO	ALL, for existing company already created from a previous call.	This corresponds to the 'company.id' field value present in a 'create transaction' API response called previously. When creating a new company for the first time, ignore this parameter and provide 'company.name' instead.
USER_ID	String	URL	no	PURCHASE and BILLING_INFO	ALL, for existing user already created from a previous call.	This corresponds to the 'user.id' field value present in a 'create transaction' API response called previously. When creating a new user for the first time, ignore this parameter and provide all user.* fields instead.
returnUrl	String	payload	no	PURCHASE and BILLING_INFO	ALL	URL that marketplace will use to return customer on developer's website at the end of the flow. When specified, overrides the return url configured in marketplace via the UI screen.

The general flow for a product purchase is as follows:

1. The customer selects a product from the developer's website to view the product details. This step is optional -- it is of course up to the developer's discretion to build his own product browsing layout.
2. The customer wishes to purchase the actual product and clicks on a "Buy Now" button.
3. The "Buy Now" button submits a request to the developer's website backend system to initialize the transaction. The request should contain the AppDirect product ID parameter as described previously, or any developer-specific product number that can be used to fetch the associated AppDirect product ID from the developer's database.
4. Once the developer's backend systemreceives the request, it can call the AppDirect REST API to initialize (create) the hosted checkout transaction. Some fields will have to be passed in the API request, such as the developer's generated "token". All your requests to AppDirect must be signed using the consumer key and secret described above.

Following are examples of the API requests that would be made to initiate a purchase.

Example: Create new user and new company

# Token request to initiate a checkout transaction
# Creates a new user and a new company
# Endpoint:   api/hostedCheckout/v1/transactions

{
    "productId": "137",
    "token": "g04958thrkjh982h2323kjgj2hg3jhg2349u",
    "type": "PURCHASE",
    "user": \{
        "email": "bob.gratton@ad.com",
        "firstName": "Bob",
        "lastName": "Gratton"
    \},
    "company": \{ "name": "Pasta Dental" \},
    "returnUrl": "https://developer.com/return"
}

Example: Create new user for existing company

# Token request to initiate a checkout transaction
# Creates a new user for an existing company
# Endpoint:   api/hostedCheckout/v1/companies/7e707597-544f-4c51-bdb1-66adb264fb69/transactions

{
    "productId": "137",
    "token": "g04958thrkjh982h2323kjgj2hg3jhg2349u",
    "type": "PURCHASE",
    "user": \{
        "email": "bob.gratton@ad.com",
        "firstName": "Bob",
        "lastName": "Gratton"
    \}
}

Example: Existing user

# Token request to initiate a checkout transaction
# Existing/Returning customer (only IDs are being passed)
# Endpoint:   api/hostedCheckout/v1/companies/7e707597-544f-4c51-bdb1-66adb264fb69/users/9834h2w3-j345-34l2-lk32-98hkj234gi34/transactions

{
    "productId": "137",
    "token": "g04958thrkjh982h2323kjgj2hg3jhg2349u",
    "type": "PURCHASE"
}

Example: Change billing details

# Token request to initiate a Change billing details flow
# (as you can see, there's no productId and different transaction type..)
# Endpoint:   api/hostedCheckout/v1/companies/7e707597-544f-4c51-bdb1-66adb264fb69/users/9834h2w3-j345-34l2-lk32-98hkj234gi34/transactions

{
    "token": "g04958thrkjh982h2323kjgj2hg3jhg2349u",
    "type": "BILLING_INFO"
}